Model Configuration Variables

This document describes the environment variables available for fine-grained control over AI model availability and capabilities in HAWKI. These variables let administrators customize model behavior without modifying source code.

Table of Contents

1. Overview
2. Configuration Architecture
3. Applying Configuration Changes
4. Variable Naming Convention
5. Model Activation Variables
6. Tool Capability Variables
7. Provider-Level Settings
8. Default and System Model Selection
9. Best Practices
10. Examples

---

Overview

HAWKI's model configuration uses three coordinated layers:

1. .env file — where you set values
2. Config files (config/model_providers.php, config/model_lists/*.php) — read the env values via env()
3. Database (ai_models, ai_providers) — the runtime source of truth, populated from config via sync

Important: Changing an environment variable is not enough on its own. After editing .env, you must clear the config cache and re-sync the database for the change to take effect at runtime. See Applying Configuration Changes.

Why Use Environment Variables?

• No source code changes: Enable or disable models and capabilities from .env only
• Source control safety: Site-specific settings stay out of version-controlled files
• Per-environment control: Use different .env files for development, staging, and production
• Update-safe: Config overrides survive HAWKI upgrades without merge conflicts

Default Behavior

These variables are not required in .env. When absent, the defaults defined in the model list files are used. Only add a variable when you need to override the default.

---

Configuration Architecture

Layer 1 — Environment Variables (.env)

Your .env file is where all site-specific values live. Model configuration variables go here:

MODELS_OPENAI_GPT5_ACTIVE=false
MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION=true
DEFAULT_MODEL=gpt-4.1-nano

Layer 2 — Config Files (deployment-time)

The config files consume env values via env() and define the complete model catalog:

• config/model_providers.php — providers, API endpoints, default/system model selection
• config/model_lists/*.php — individual model definitions and capability flags

These files are read by the sync command to populate the database. They are not read at runtime by the application itself.

Layer 3 — Database (runtime)

After running php hawki models sync, the database holds a persistent copy of every provider and model. At runtime, HAWKI reads exclusively from the database — config files are never consulted.

.env  →  config files  →  (ai:models:sync)  →  database  →  application runtime

Key implications:

• The active flag in config (controlled by env vars) always overwrites the database value on each sync.
• A model can be deactivated in the database without touching config, but a subsequent --force sync will restore the config value.
• Provider API keys are never stored in the database. They are always read from .env at request time.

---

Applying Configuration Changes

After any change to model-related environment variables, run:

php hawki clear-cache
php hawki models sync --force

The clear-cache step ensures Laravel picks up your new .env values. The --force flag re-syncs all providers and models regardless of whether records already exist.

To verify the result:

php hawki models list
php hawki models list --active

---

Variable Naming Convention

Model Activation Variables

MODELS_{PROVIDER}_{MODEL_ID}_ACTIVE

Components:

• MODELS_ — fixed prefix
• {PROVIDER} — provider name in uppercase (e.g. OPENAI, GWDG, GOOGLE)
• {MODEL_ID} — model ID with special characters replaced by underscores, uppercased
• _ACTIVE — suffix

Model ID transformation rules:

1. Convert to uppercase
2. Replace hyphens (-) with underscores (_)
3. Replace dots (.) with underscores (_)
4. Remove any other special characters

Examples:

Original Model ID	Environment Variable
gpt-5	MODELS_OPENAI_GPT5_ACTIVE
gpt-4.1-nano	MODELS_OPENAI_GPT4_1_NANO_ACTIVE
gemini-2.0-flash	MODELS_GOOGLE_GEMINI_2_0_FLASH_ACTIVE
meta-llama-3.1-8b-instruct	MODELS_GWDG_META_LLAMA_3_1_8B_INSTRUCT_ACTIVE
qwen2.5-vl-72b-instruct	MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_ACTIVE

Tool Capability Variables

MODELS_{PROVIDER}_{MODEL_ID}_TOOLS_{TOOL_NAME}

Components:

• MODELS_{PROVIDER}_{MODEL_ID} — same as activation prefix
• _TOOLS_ — separator
• {TOOL_NAME} — capability name in uppercase

Built-in capability names:

Capability	Variable suffix
File upload	_TOOLS_FILE_UPLOAD
Image vision	_TOOLS_VISION
Web search	_TOOLS_WEB_SEARCH

Examples:

Model ID	Capability	Variable
gpt-5	vision	MODELS_OPENAI_GPT5_TOOLS_VISION
gpt-5	file_upload	MODELS_OPENAI_GPT5_TOOLS_FILE_UPLOAD
gemini-2.0-flash	web_search	MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_WEB_SEARCH
qwen2.5-vl-72b-instruct	vision	MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION

---

Model Activation Variables

These variables control whether a model appears in the model selection interface.

MODELS_{PROVIDER}_{MODEL_ID}_ACTIVE=true|false

Model activation defaults are defined in the provider's model list file. The list files are located at:

Provider	File
OpenAI	config/model_lists/openai_models.php
GWDG	config/model_lists/gwdg_models.php
Google	config/model_lists/google_models.php
Ollama	config/model_lists/ollama_models.php
OpenWebUI	config/model_lists/openwebui_models.php

Common use cases:

# Disable expensive models in development
MODELS_OPENAI_GPT5_ACTIVE=false
MODELS_GOOGLE_GEMINI_2_5_PRO_ACTIVE=false

# Enable specific models for testing
MODELS_OPENAI_GPT4_1_NANO_ACTIVE=true
MODELS_GWDG_META_LLAMA_3_1_8B_INSTRUCT_ACTIVE=true

After changing these values, run:

php hawki clear-cache && php hawki models sync --force

---

Tool Capability Variables

These variables control built-in capabilities per model. They map to the tools array in each model's config definition.

MODELS_{PROVIDER}_{MODEL_ID}_TOOLS_{TOOL_NAME}=true|false

Note: These variables control built-in model capabilities (file upload, vision, web search). For user-installable tools such as function-calling tools and MCP tools, see AI Models & Tools.

FILE_UPLOAD

Enables document and image file uploads for a model.

Supported document types: PDF, DOCX Supported image types: JPEG, JPG, PNG

MODELS_OPENAI_GPT5_TOOLS_FILE_UPLOAD=false
MODELS_GWDG_META_LLAMA_3_1_8B_INSTRUCT_TOOLS_FILE_UPLOAD=true
MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_FILE_UPLOAD=false

Default policy: External cloud API endpoints (e.g. OpenAI, Google) have file upload disabled by default. This protects data sovereignty — uploaded content must not leave academic infrastructure or be reused for model training. Enable external providers explicitly and at your own risk.

File upload requires a working converter:

FILE_CONVERTER=hawki_converter
HAWKI_FILE_CONVERTER_API_URL=127.0.0.1:8001/extract
HAWKI_FILE_CONVERTER_API_KEY=your-key

# Or use GWDG Docling:
# FILE_CONVERTER=gwdg_docling

VISION

Enables image analysis for models that support multimodal input.

Supported input: PNG, JPG, JPEG

MODELS_OPENAI_GPT5_TOOLS_VISION=true
MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION=true
MODELS_GOOGLE_GEMINI_2_0_FLASH_LITE_TOOLS_VISION=false

Only enable for models that declare image in their input array in the model list config.

WEB_SEARCH

Enables native web search integration.

MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_WEB_SEARCH=true
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_WEB_SEARCH=true

Currently, native web search is available only for Google Gemini and OpenAI GPT4.1 and GPT5 models. For other providers, web search can be added via a function-calling tool or MCP server — see AI Models & Tools.

How capability flags appear in config

// config/model_lists/openai_models.php
'tools' => [
    'stream'      => true,
    'file_upload' => env('MODELS_OPENAI_GPT5_TOOLS_FILE_UPLOAD', false),
    'vision'      => env('MODELS_OPENAI_GPT5_TOOLS_VISION', true),
],

---

Provider-Level Settings

Enable or disable entire providers and configure their API endpoints.

# Enable/disable providers
OPENAI_ACTIVE=true
GWDG_ACTIVE=true
GOOGLE_ACTIVE=true
OLLAMA_ACTIVE=false
OPEN_WEB_UI_ACTIVE=false

# Provider API keys
OPENAI_API_KEY=your-key
GWDG_API_KEY=your-key
GOOGLE_API_KEY=your-key

# Custom API endpoints (optional)
OPENAI_URL=https://api.openai.com/v1/responses
GWDG_URL=https://your-gwdg-instance.de/v1/chat/completions
OLLAMA_API_URL=http://localhost:11434/api/chat

Disabling a provider sets active=false for the provider record in the database after the next sync. All its models will also be treated as inactive at runtime.

---

Default and System Model Selection

Set which models are used by default for each task type:

# User-facing default models
DEFAULT_MODEL=gpt-4.1-nano
DEFAULT_WEBSEARCH_MODEL=gemini-2.0-flash
DEFAULT_FILEUPLOAD_MODEL=qwen3-omni-30b-a3b-instruct
DEFAULT_VISION_MODEL=qwen3-omni-30b-a3b-instruct

# Internal system tasks
TITLE_GENERATOR_MODEL=gpt-4.1-nano
PROMPT_IMPROVEMENT_MODEL=gpt-4.1-nano
SUMMARIZER_MODEL=gpt-4.1-nano

The model ID used here must match the id field of an active model in your config. These values are read directly from .env at runtime (not synced to the database), so they take effect immediately after php hawki clear-cache.

---

Best Practices

1. Only override what you need

The defaults in model list files work well for most deployments. Add env variables only when you need to change a default.

2. Document your overrides

# Disable GPT-5 to control API costs in development
MODELS_OPENAI_GPT5_ACTIVE=false

# Use self-hosted vision model
MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION=true
DEFAULT_VISION_MODEL=qwen2.5-vl-72b-instruct

3. Always sync after changes

php hawki clear-cache
php hawki models sync --force
php hawki models list --active    # verify result

4. Use environment-specific .env files

Development — minimize cost:

DEFAULT_MODEL=gpt-4.1-nano
MODELS_OPENAI_GPT5_ACTIVE=false
MODELS_GOOGLE_GEMINI_2_5_PRO_ACTIVE=false

Production — enable all appropriate models:

MODELS_OPENAI_GPT5_ACTIVE=true
MODELS_OPENAI_GPT4_1_ACTIVE=true
MODELS_GOOGLE_GEMINI_2_5_PRO_ACTIVE=true

5. Data sovereignty defaults

External provider file upload is disabled by default for data protection reasons. Only enable it after reviewing the provider's data usage policies:

# Only enable if you have confirmed the provider does not retain uploaded data
MODELS_OPENAI_GPT5_TOOLS_FILE_UPLOAD=true

Use self-hosted (GWDG, Ollama) models for sensitive file processing where possible.

6. Security — disable external models when needed

# Use only self-hosted / academic infrastructure
OPENAI_ACTIVE=false
GOOGLE_ACTIVE=false

GWDG_ACTIVE=true
GWDG_API_KEY=your-academic-key
OLLAMA_ACTIVE=true
OLLAMA_API_URL=http://localhost:11434/api/chat

---

Examples

Example 1: Cost-Optimized Development

# Use cheap models as defaults
DEFAULT_MODEL=gpt-4.1-nano
DEFAULT_WEBSEARCH_MODEL=gemini-2.0-flash
DEFAULT_FILEUPLOAD_MODEL=meta-llama-3.1-8b-instruct
DEFAULT_VISION_MODEL=qwen2.5-vl-72b-instruct

# Disable expensive models
MODELS_OPENAI_GPT5_ACTIVE=false
MODELS_OPENAI_GPT4_1_ACTIVE=false
MODELS_GOOGLE_GEMINI_2_5_PRO_ACTIVE=false

# Disable file upload for external APIs
MODELS_OPENAI_GPT4_1_NANO_TOOLS_FILE_UPLOAD=false
MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_FILE_UPLOAD=false

# Enable for self-hosted model
MODELS_GWDG_META_LLAMA_3_1_8B_INSTRUCT_TOOLS_FILE_UPLOAD=true

Example 2: Privacy-First Deployment

# Disable commercial cloud providers
OPENAI_ACTIVE=false
GOOGLE_ACTIVE=false

# Academic cloud
GWDG_ACTIVE=true
GWDG_API_KEY=your-key

# Self-hosted
OLLAMA_ACTIVE=true
OLLAMA_API_URL=http://localhost:11434/api/chat

DEFAULT_MODEL=meta-llama-3.1-8b-instruct
DEFAULT_VISION_MODEL=qwen2.5-vl-72b-instruct
DEFAULT_FILEUPLOAD_MODEL=meta-llama-3.1-8b-instruct

# Disable web search (no external data sharing)
MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_WEB_SEARCH=false

Example 3: Feature-Rich Production

OPENAI_ACTIVE=true
GWDG_ACTIVE=true
GOOGLE_ACTIVE=true

MODELS_OPENAI_GPT5_ACTIVE=true
MODELS_OPENAI_GPT4_1_ACTIVE=true
MODELS_GOOGLE_GEMINI_2_5_PRO_ACTIVE=true

MODELS_OPENAI_GPT5_TOOLS_FILE_UPLOAD=true
MODELS_OPENAI_GPT5_TOOLS_VISION=true
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_FILE_UPLOAD=true
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_VISION=true
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_WEB_SEARCH=true

MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION=true
MODELS_GWDG_INTERNVL2_5_8B_TOOLS_VISION=true

Example 4: Research & Document Analysis

# Enable reasoning models
MODELS_GWDG_DEEPSEEK_R1_ACTIVE=true
MODELS_GWDG_QWQ_32B_ACTIVE=true

# Enable file processing for relevant models
MODELS_GWDG_DEEPSEEK_R1_TOOLS_FILE_UPLOAD=true
MODELS_GWDG_LLAMA_3_3_70B_INSTRUCT_TOOLS_FILE_UPLOAD=true
MODELS_GWDG_MISTRAL_LARGE_INSTRUCT_TOOLS_FILE_UPLOAD=true
MODELS_OPENAI_GPT4_1_TOOLS_FILE_UPLOAD=true

# Web search for current information
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_WEB_SEARCH=true

DEFAULT_MODEL=deepseek-r1
DEFAULT_FILEUPLOAD_MODEL=mistral-large-instruct
DEFAULT_WEBSEARCH_MODEL=gemini-2.5-pro

Example 5: Task-Specific Multi-Model Setup

# Fast, cheap model for general chat
DEFAULT_MODEL=gpt-4.1-nano

# Best model for web search
DEFAULT_WEBSEARCH_MODEL=gemini-2.5-pro
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_WEB_SEARCH=true

# Cost-effective model for documents
DEFAULT_FILEUPLOAD_MODEL=meta-llama-3.1-8b-instruct
MODELS_GWDG_META_LLAMA_3_1_8B_INSTRUCT_TOOLS_FILE_UPLOAD=true

# High-quality vision
DEFAULT_VISION_MODEL=qwen2.5-vl-72b-instruct
MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION=true

---

Related Documentation

• AI Models & Tools — complete architecture guide for models and tools, including MCP servers and function-calling tools
• dot Env Configuration — complete .env reference
• HAWKI CLI — CLI command reference
• Model Connection — provider adapter implementation details